-- Plugins

Monday, September 23, 2024

6:24 AM

OneNote can execute plugins that can process a page or hierarchy using a program that you write, ether an executable or a script. This provides a simple way to experiment with page adjustments.

 

 

OneNote will run the program as a subprocess. As usual, a Windows subprocess is specified as a Command and its command line Arguments. For example, powershell -f <path>, where "powershell" is the Command and "-f <path>" are the Arguments passed to the powershell command. If you write an executable, then just specify the Command and leave the Arguments field blank.

 

OneMore always passes at least one argument to your script or executable. This argument is always the full path to a temporary XML file that contains the page or hierarchy XML.

 

You may also pass additional user-defined arguments to your script or executable; these are constant values and are specified in the User Arguments field. Be sure to quote strings if they contain spaces. The User Arguments field lets you create multiple plugin definitions that invoke the same script or executable but with different user arguments.

 

 

The workflow is very simple.

 

1. Create a plugin script or executable that accepts the XML file path and any user arguments.
2. Define a Plugin with the desired command, arguments, and user arguments, optionally save it with a unique name.
3. Run the plugin.
4. The plugin must complete within 20 seconds or it will timeout and be aborted.
5. If the plugin is working on a page, it must write any desired changes back to the temporary file path it was given.
6. If the plugin completes successfully and has made changes to the XML file on disk then OneMore will update the current page with your updated XML from the file;
7. If the plugin completes and has not made changes to the file then no changes are made to the current page.
8. If you chose to create a new page then it will be created regardless of whether the plugin updated the XML file.

 

Any output that your plugin writes to stdout will be captured in the OneMore log file.

 

Note, if you run the plugin and a Web browser is invoked (IE) showing the XML file contents then you probably forgot to specify the right arguments to powershell.exe or python.exe.

 

You can use the special keyword $name in the Page Name field. This will be replaced with the name of the current page when you invoke the plugin from the Favorites menu or choose it from the drop-down list. For example, if you're on page "Forecasting" and the Page Name is set to "Quarterly $name" then the created page when it will be named "Quarterly Forecasting"

 

The default timeout - time allotted in which a plugin must complete - is 15 seconds. You can change that by entering the number of seconds into the Timeout field. If set to zero then the timeout is set to one hour.

 

The following environment variables are set when calling a plugin.

 

• PLUGIN_ASCHILD - set to true when the Create as child option is checked
• PLUGIN_CREATE - set to true when the Create as new page option is checked
• PLUGIN_PAGENAME - specifies the name of the page to create or update
• PLUGIN_SOURCE_PAGEID - the OneNote ID of the source page
• PLUGIN_SOURCE_SECTIONID - the OneNote ID of the source page's section
• PLUGIN_SOURCE_NOTEBOOKID - the OneNote ID of the source page's notebook
• PLUGIN_SOURCE_PAGENAME - the title of the source page
• PLUGIN_SOURCE_PAGEPATH - the hierarchy path of the source page, including notebook, section, and page name
• PLUGIN_SOURCE_PAGEURL - the OneNote URL of the source page
• PLUGIN_SKIPLOCK - set to true when the Skip locked sections option is checked

 

The OneNote page schema is defined in the 0336.OneNoteApplication_2013.xsd file in the References folder of the project repo.

 

 

#omwiki #omcommands

 

© 2020 Steven M Cohn. All rights reserved.

Please consider a sponsorship or one-time donation to support ongoing development